<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="libman.css">
<TITLE>
Low-Level Solver Interface
</TITLE>
</HEAD>
<BODY >
<A HREF="libman055.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="libman052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="libman057.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc120">9.4</A>&nbsp;&nbsp;Low-Level Solver Interface</H2><UL>
<LI><A HREF="libman056.html#toc66">Setting Up a Solver State</A>
<LI><A HREF="libman056.html#toc67">Adding Constraints to a Solver State</A>
<LI><A HREF="libman056.html#toc68">Running a Solver State Explicitly</A>
<LI><A HREF="libman056.html#toc69">Accessing the Solver State</A>
<LI><A HREF="libman056.html#toc70">Expandable Problem and Constraints</A>
<LI><A HREF="libman056.html#toc71">Changing Solver State Settings</A>
<LI><A HREF="libman056.html#toc72">Destroying a Solver State</A>
<LI><A HREF="libman056.html#toc73">Miscellaneous Predicates</A>
</UL>


For many applications, the facilities presented so far should be
appropriate for using Simplex/MIP through ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.
However, sometimes it may be more convenient or efficient
to directly access the solver state
instead of going through the abstraction of the eplex instances. 
This section describes lower level operations like how to set up
solvers manually. In fact, these lower level predicates are used to
implement the predicates provided with eplex instances.<BR>
<BR>
These predicates accesses the external solver state via a handle, which is
returned when the solver state is set up, and subsequently used to access a
particular solver state by the other predicates. The handle should be
treated as a opaque data structure that is used by the eplex library to
refer to a particular solver state.<BR>
<BR>
<A NAME="toc66"></A>
<H3 CLASS="subsection"><A NAME="htoc121">9.4.1</A>&nbsp;&nbsp;Setting Up a Solver State</H3>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_demon_setup-5.html"><B>lp_demon_setup(+Objective, -Cost, +ListOfOptions, 
+TriggerModes, -Handle)</B></A><A NAME="@default302"></A></H4>
This is used to set up a demon solver, and <TT>eplex_solver_setup/4</TT> calls
this predicate. There is one extra argument compared to <TT>eplex_solver_setup/4</TT>: the solver state handle <TT>Handle</TT>, which is
returned by this predicate when the new solver state is created.
The other arguments are the same as in <TT>eplex_solver_setup/4</TT>, except
that there is an additional option in <TT>ListOfOptions</TT>: <TT>collect_from/1</TT>. This is used to specify which, if any, eplex instance
the solver state should be collecting constraints from. If an eplex
instance is specified (as <TT>pool(Instance)</TT>), then the solver state is
associated with that instance. If the eplex instance is <I>not</I> to be
associated with an eplex instance, <TT>none</TT> should be given as the
argument to <TT>collect_from</TT>. This allows a solver state to be set up
without the overhead of an eplex instance. The solver state will not
collect any constraints automatically when it is invoked; instead the
constraints must be added explicitly via the handle (using <TT>lp_add_constraints/3</TT>).<BR>
<BR>
By default, the external solver is invoked once after set up
by <TT>lp_demon_setup</TT>,
if any <TT>TriggerModes</TT> is specified. Otherwise, the solver is not
invoked and the predicate returns after set up.<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_setup-4.html"><B>lp_setup(+NormConstraints, +Objective, +ListOfOptions, -Handle)</B></A><A NAME="@default303"></A></H4>
<A NAME="lpsetup"></A>
This is an even lower-level primitive, setting up a solver state
without any automatic triggering.
It creates a new solver state for the set of constraints NormConstraints
(see <A HREF="#constrcoll">below</A> for how to obtain a set of
normalised constraints).
Apart from the explicitly listed constraints, the variable's ranges will
be taken into account as the variable bounds for the simplex algorithm.
Undeclared variables are implicitly declared as <A HREF="../bips/lib/eplex/reals-1.html"><B>reals/1</B></A><A NAME="@default304"></A>.<BR>
<BR>
However, when variables have been declared integers in other solvers (e.g.
using <A HREF="../bips/lib/ic/integers-1.html"><B>ic:integers/1</B></A><A NAME="@default305"></A>),
that is not taken into account by the solver by default.
This means that the solver will only work on the <EM>relaxed problem</EM>
(ie. ignoring the integrality constraints),
unless specified otherwise in the options.
Objective is either <TT>min(Expr)</TT> or <TT>max(Expr)</TT>
where Expr is a linear (or quadratic) expression.
ListOfOptions is a list of solver options, the same as for
<A HREF="../bips/lib/eplex/lp_demon_setup-5.html"><B>lp_demon_setup/5</B></A><A NAME="@default306"></A> and <A HREF="../bips/lib/eplex/eplex_solver_setup-4.html"><B>eplex_solver_setup/4</B></A><A NAME="@default307"></A>, except for the <TT>collect_from</TT> and <TT>initial_solve</TT> options, which are specific for the
demon solvers.<BR>
<BR>
<A NAME="toc67"></A>
<H3 CLASS="subsection"><A NAME="htoc122">9.4.2</A>&nbsp;&nbsp;Adding Constraints to a Solver State</H3>
Constraints can be added directly to a solver state without posting them to
an eplex instance. This is done by:<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_add_constraints-3.html"><B>lp_add_constraints(+Handle, +Constraints, +NewIntegers)</B></A><A NAME="@default308"></A></H4>
Add new constraints (with possibly new variables) to the solver state
represented by Handle
The new constraints will be taken into account the next time the
solver is run. The constraints will be removed on backtracking.<BR>
<BR>
The constraints are first normalised, and simple constraints filtered out (as
discussed in section&nbsp;<A HREF="libman054.html#linear-constraints">9.2.1</A>) before they are added
to the external solver (by calling lp_add/3 described below).<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_add-3.html"><B>lp_add(+Handle, +NewNormConstraints, +NewIntegers)</B></A><A NAME="@default309"></A></H4>
<A NAME="lp-add"></A>
This adds the constraints (both linear and integrality) to the
external solver represented by Handle. The linear arithmetic constraints
must be normalised. Note that it is possible to add trivial constraints,
which would be filtered out by the higher level <TT>lp_add_constraints/3</TT>
using this predicate. Integrality constraints on non-problem variables are
filtered out and a warning given.<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_add_vars-2.html"><B>lp_add_vars(+Handle, +Vars)</B></A><A NAME="@default310"></A></H4>
This adds the variables in Vars to the external solver state represented by
Handle. The variables should not contain variables which are already
problem variables. The variables are given the default bounds of
-infinity..infinity. <BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_var_set_bounds-4.html"><B>lp_var_set_bounds(+Handle, +Var, ++Lo,++Hi)</B></A><A NAME="@default311"></A></H4>
This updates the bounds for the problem variable Var in the external
solver state represented by Handle. Failure occurs if Var is not a problem
variable. <BR>
<BR>
<A NAME="toc68"></A>
<H3 CLASS="subsection"><A NAME="htoc123">9.4.3</A>&nbsp;&nbsp;Running a Solver State Explicitly</H3>


<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_solve-2.html"><B>lp_solve(+Handle,
-Cost)</B></A><A NAME="@default312"></A></H4>
Apply the external solver's LP or MIP solver to the problem represented by Handle.
Precisely which method is used depends on the options given to lp_setup/4.
lp_solve/2 fails (by default) if there is no solution or succeeds
if an optimal solution is found, returning the solution's cost in Cost
(unlike with lp_demon_setup/6, Cost gets instantiated to a number).
After a success, various solution and status information can be retrieved
using lp_get/3 and lp_var_get/4.<BR>
<BR>

The set of constraints considered by the solver is the one given when the
solver was created plus any new constraints that were added
(e.g by lp_add_constraints/3) in the meantime.
<BR>
<BR>
If there was an error condition, or limits were exceeded,
lp_solve/2 raises an event. See section <A HREF="libman061.html#lpevents">9.9</A> for details.<BR>
<BR>

<H4 CLASS="subsubsection">lp_probe(+Handle, +Probes, -Cost)</H4>
<A NAME="@default313"></A>
Similar to lp_solve/2, but optimize for a modified problem as specified by
Probes. This is the
predicate called by <A HREF="../bips/lib/eplex/eplex_probe-2.html"><B>eplex_probe/2</B></A><A NAME="@default314"></A>
<A NAME="toc69"></A>
<H3 CLASS="subsection"><A NAME="htoc124">9.4.4</A>&nbsp;&nbsp;Accessing the Solver State</H3>
In section&nbsp;<A HREF="libman055.html#eplex-instance-solver-info">9.3.1</A>, we discussed how solver state
information can be accessed via the eplex instance. Here are the lower
level predicates that directly access this information via the solver
state's handle:<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_get-3.html"><B>lp_get(+Handle, +What, -Value)</B></A><A NAME="@default315"></A></H4>
Retrieve information about solver state and results. See the reference
manual description of <TT>lp_get/3</TT> for a detailed description of the
available values for <TT>What</TT>.<BR>
<BR>
For example, it is possible to obtain the solution values from the last
successful invocation of the external solver using the following:
<PRE CLASS="verbatim">
    instantiate_solution(Handle) :-
        lp_get(Handle, vars, Vars),
        lp_get(Handle, typed_solution, Values),
        Vars = Values.
    </PRE>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_var_get-4.html"><B>lp_var_get(+Handle,+Var, +What, -Value)</B></A><A NAME="@default316"></A></H4>
Retrieve information about solver state represented by Handle,
related to a specific variable Var. Again, see the reference manual for the
available parameters.<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_var_get_bounds-4.html"><B>lp_var_get_bounds(+Handle, +Var, -Lo, -Hi)</B></A><A NAME="@default317"></A></H4>
Retrieve the bounds of the problem variable Var from the solver state
represented by Handle. <BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/reduced_cost_pruning-2.html"><B>reduced_cost_pruning(+Handle,?GlobalCost)</B></A><A NAME="@default318"></A></H4>
This predicate implements a technique to prune variable bounds
based on a global cost bound and the reduced costs of some solution to
a problem relaxation. The assumptions are that there is a global
problem whose cost variable is GlobalCost, and that Handle refers to
a linear relaxation of this global problem.
The pruning potentially affects all variables involved in the relaxed
problem.<BR>
<BR>
<A NAME="toc70"></A>
<H3 CLASS="subsection"><A NAME="htoc125">9.4.5</A>&nbsp;&nbsp;Expandable Problem and Constraints</H3>
<A NAME="coladd"></A>
We provide low-level primitives to `expand' an eplex problem. Such a problem is
considered to have as yet unspecified components in the objective function
and posted constraints. These constraints are known as expandable constraints.
The as yet unspecified component involve variables
that have not yet been added to the problem. When these variables are
added, coefficients for the variables can be added to the expandable
constraints, as well as the objective function. These primitives are the
basis for implementing <B>column generation</B>, and are used by the column
generation library, lib(colgen). <BR>
<BR>
These primitives modify an existing eplex problem <I>non-monotonically</I>, and can only be used on problems that are not
represented by an eplex instance, and was not setup as a demon solver
(i.e. no trigger conditions are specified). <BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_add_constraints-4.html"><B>lp_add_constraints(+Handle, +Constraints, +Ints, -Idxs)</B></A><A NAME="@default319"></A></H4>
<A NAME="@default320"></A>
This adds expandable constraints Constraints to the solver state
represented by Handle. The predicate returns a list of indices for these
constraints in Idxs. The indices are used to refer to the constraints when
new variables are added to expand the problem.<BR>
<BR>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_add_columns-2.html"><B>lp_add_columns(+Handle, +Columns)</B></A><A NAME="@default321"></A></H4>
<A NAME="@default322"></A>
This expands the problem by adding new variables (columns) to the solver
state represented by Handle. Columns is a list of
variable:column-specification pair, where variable is the variable to be
added as a new column, and column-specification the specification for the
non-zero components of the column, i.e. coefficients for the expandable
constraints (referred to using the index obtained from
lp_add_constraints/4) and the objective for this variable.<BR>
<BR>
<A NAME="toc71"></A>
<H3 CLASS="subsection"><A NAME="htoc126">9.4.6</A>&nbsp;&nbsp;Changing Solver State Settings</H3>
In addition to accessing information from the solver state, some options (a
subset of those specified during solver set up) can be changed by:

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_set-3.html"><B>lp_set(+Handle, +What, +Value)</B></A><A NAME="@default323"></A></H4>
This primitive can be used to change some of the initial options
even after setup. <EM>Handle</EM> refers to an existing solver state. See the
reference manual for details.<BR>
<BR>
<A NAME="toc72"></A>
<H3 CLASS="subsection"><A NAME="htoc127">9.4.7</A>&nbsp;&nbsp;Destroying a Solver State</H3>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_cleanup-1.html"><B>lp_cleanup(+Handle)</B></A><A NAME="@default324"></A></H4>
Destroy the specified solver state, free all memory, etc. If the solver
state is associated with an eplex handle, the solver state is disassociated
with the eplex instance. However, unlike <A HREF="../bips/lib/eplex/eplex_cleanup-0.html"><B>eplex_cleanup/0</B></A><A NAME="@default325"></A>, the
outstanding constraints not yet collected by the solver is not removed.<BR>
<BR>
As with <TT>eplex_cleanup/0</TT>, care should be taken before using this
non-logical predicate. <BR>
<BR>
<A NAME="toc73"></A>
<H3 CLASS="subsection"><A NAME="htoc128">9.4.8</A>&nbsp;&nbsp;Miscellaneous Predicates</H3>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_read-3.html"><B>lp_read(+File, +Format, -Handle)</B></A><A NAME="@default326"></A></H4>
Read a problem from a file and setup a solver for it. Format is
<TT>lp</TT> or <TT>mps</TT>.
The result is a handle similar to the one obtained by lp_setup/4.

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/lp_write-3.html"><B>lp_write(+Handle, +Format, +File)</B></A><A NAME="@default327"></A></H4>
Write out the problem in the solver state represented by Handle to the file
File in format Format.<BR>
<BR>
<A NAME="constrcoll"></A>

<H4 CLASS="subsubsection"><A HREF="../bips/lib/eplex/normalise_cstrs-3.html"><B>normalise_cstrs(+Constraints, -NormConstraints, -NonlinConstr)</B></A><A NAME="@default328"></A></H4>
where Constraints is a list of terms of the form
X <CODE>$=</CODE> Y, X <CODE>$&gt;=</CODE> Y or X <CODE>$=&lt;</CODE> Y 
where X and Y are arithmetic expressions.
The linear constraints are returned in normalised form in NormConstraints,
the nonlinear ones are returned unchanged in NonlinConstr.<BR>
<BR>
<HR>
<A HREF="libman055.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="libman052.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="libman057.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
